javax.realtime
Class PeriodicParameters

java.lang.Object
  javax.realtime.ReleaseParameters
      javax.realtime.PeriodicParameters

public class PeriodicParameters

extends ReleaseParameters

This release parameter indicates that the schedulable object is released on a regular basis. For an AsyncEventHandler, this means that the handler is either released by a periodic timer, or the associated event occurs periodically. For a RealtimeThread, this means that the RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible() method will unblock the associated real-time thread at the start of each period.

When a reference to a PeriodicParameters object is given as a parameter to a schedulable object's constructor or passed as an argument to one of the schedulable object's setter methods, the PeriodicParameters object becomes the release parameters object bound to that schedulable object. Changes to the values in the PeriodicParameters object affect that schedulable object. If bound to more than one schedulable object then changes to the values in the PeriodicParameters object affect all of the associated objects. Note that this is a one-to-many relationship and not a many-to-many.

Only changes to a PeriodicParameters object caused by methods on that object cause the change to propagate to all schedulable objects using the object. For instance, calling setCost on an PeriodicParameters object will make the change, then notify that the scheduler that the parameter object has changed. At that point the object is reconsidered for every SO that uses it. Invoking a method on the RelativeTime object that is the cost for this object may change the cost but it does not pass the change to the scheduler at that time. That change must not change the behavior of the SOs that use the parameter object until a setter method on the PeriodicParameters object is invoked, or the parameter object is used in setReleaseParameters() or a constructor for an SO.

Periodic parameters use HighResolutionTime values for period and start time. Since these times are expressed as a HighResolutionTime values, these values use accurate timers with nanosecond granularity. The actual resolution available and even the quantity the timers measure depend on the clock associated with each time value.

The implementation must use modified copy semantics for each HighResolutionTime parameter value. The value of each time object should be treated as if it were copied at the time it is passed to the parameter object, but the object reference must also be retained. For instance, the value returned by getCost() must be the same object passed in by setCost(), but any changes made to the time value of the cost must not take effect in the associated PeriodicParameters instance unless they are passed to the parameter object again, e.g. with a new invocation of setCost.

Periodic release parameters are strictly informational when they are applied to async event handlers. They must be used for any feasibility analysis, but release of the async event handler is not entirely controlled by the scheduler.

Caution: This class is explicitly unsafe in multithreaded situations when it is being changed. No synchronization is done. It is assumed that users of this class who are mutating instances will be doing their own synchronization at a higher level.

Caution: An implementation is not required to ensure that each AsyncEventHandler with periodic parameters is released periodically.

Attribute	Default Value
start	new RelativeTime(0,0)
period	No default. A value must be supplied
cost	new RelativeTime(0,0)
deadline	new RelativeTime(period)
overrunHandler	None
missHandler	None

Field Summary

protected RelativeTime	period
protected HighResolutionTime	start

Fields inherited from class javax.realtime.ReleaseParameters

cost, deadline, missHandler, overrunHandler

Constructor Summary

PeriodicParameters(HighResolutionTime start, RelativeTime period)
Create a PeriodicParameters object.

PeriodicParameters(HighResolutionTime start, RelativeTime period, RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler)
Create a PeriodicParameters object.

PeriodicParameters(RelativeTime period)
Create a PeriodicParameters object.

Method Summary

RelativeTime	getPeriod() Gets the period.
HighResolutionTime	getStart() Gets the start time.
void	setDeadline(RelativeTime deadline) Sets the deadline value.
boolean	setIfFeasible(RelativeTime period, RelativeTime cost, RelativeTime deadline) This method first performs a feasibility analysis using the new period, cost and deadline attributes as replacements for the matching attributes of this.
void	setPeriod(RelativeTime period) Sets the period.
void	setStart(HighResolutionTime start) Sets the start time.

Methods inherited from class javax.realtime.ReleaseParameters

getCost, getCostOverrunHandler, getDeadline, getDeadlineMissHandler, setCost, setCostOverrunHandler, setDeadlineMissHandler, setIfFeasible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

start

protected HighResolutionTime start

period

protected RelativeTime period

Constructor Detail

PeriodicParameters

public PeriodicParameters(HighResolutionTime start,
                          RelativeTime period)

Create a PeriodicParameters object. This constructor has the same effect as invoking PeriodicParameters(start, period, null, null, null, null)

Parameters:

start - Time at which the first release begins (i.e. the real-time thread becomes eligible for execution.) If a RelativeTime, this time is relative to the first time the thread becomes activated (that is, when start() is called). If an AbsoluteTime, then the first release is the maximum of the start parameter and the time of the call to the associated RealtimeThread.start() method. If null, the default value is a new instance of RelativeTime(0,0).

period - The period is the interval between successive unblocks of the RealtimeThread.waitForNextPeriod() and RealtimeThread.waitForNextPeriodInterruptible() methods. There is no default value. If period is null an exception is thrown.

Throws:

java.lang.IllegalArgumentException - Thrown if the period is null or its time value is not greater than zero.

IllegalAssignmentError - Thrown if start or period cannot be stored in this.

PeriodicParameters

public PeriodicParameters(HighResolutionTime start,
                          RelativeTime period,
                          RelativeTime cost,
                          RelativeTime deadline,
                          AsyncEventHandler overrunHandler,
                          AsyncEventHandler missHandler)

Create a PeriodicParameters object.

Parameters:

start - Time at which the first release begins (i.e. the real-time thread becomes eligible for execution.) If a RelativeTime, this time is relative to the first time the thread becomes activated (that is, when start() is called). If an AbsoluteTime, then the first release is the maximum of the start parameter and the time of the call to the associated RealtimeThread.start() method. If null, the default value is a new instance of RelativeTime(0,0).

period - The period is the interval between successive unblocks of the RealtimeThread.waitForNextPeriod() and RealtimeThread.waitForNextPeriodInterruptible() methods. There is no default value. If period is an exception is thrown.

cost - Processing time per release. On implementations which can measure the amount of time a schedulable object is executed, this value is the maximum amount of time a schedulable object receives per release. On implementations which cannot measure execution time, this value is used as a hint to the feasibility algorithm. On such systems it is not possible to determine when any particular object exceeds or will exceed cost time units in a release. If null, the default value is a new instance of RelativeTime(0,0).

deadline - The latest permissible completion time measured from the release time of the associated invocation of the schedulable object. If null, the default value is new instance of RelativeTime(period).

overrunHandler - This handler is invoked if an invocation of the schedulable object exceeds cost in the given release. Implementations may ignore this parameter. If null, the default value no overrun handler.

missHandler - This handler is invoked if the run() method of the schedulable object is still executing after the deadline has passed. Although minimum implementations do not consider deadlines in feasibility calculations, they must recognize variable deadlines and invoke the miss handler as appropriate. If null, the default value no deadline miss handler.

Throws:

java.lang.IllegalArgumentException - Thrown if the period is null or its time value is not greater than zero, or if the time value of cost is less than zero, or if the time value of deadline is not greater than zero.

IllegalAssignmentError - Thrown if start, period, cost, deadline, overrunHandler or missHandler cannot be stored in this.

PeriodicParameters

public PeriodicParameters(RelativeTime period)

Create a PeriodicParameters object. This constructor has the same effect as invoking PeriodicParameters(null, period, null, null, null, null)

Parameters:

period - The period is the interval between successive unblocks of the RealtimeThread.waitForNextPeriod() and RealtimeThread.waitForNextPeriodInterruptible() methods. There is no default value. If period is null an exception is thrown.

Throws:

java.lang.IllegalArgumentException - Thrown if the period is null or its time value is not greater than zero.

IllegalAssignmentError - Thrown if start or period cannot be stored in this.

Method Detail

getPeriod

public RelativeTime getPeriod()

Gets the period.

Returns:

The current value in period.

getStart

public HighResolutionTime getStart()

Gets the start time.

Returns:

The current value in start. This is the value that was specified in the constructor or by setStart(), not the actual absolute time corresponding to the start of one of the schedulable objects associated with this PeriodicParameters object.

setDeadline

public void setDeadline(RelativeTime deadline)

Sets the deadline value. If this parameter object is associated with any schedulable object by being passed through the schedulable object's constructor or set with a method such as RealtimeThread.setReleaseParameters(ReleaseParameters)) the deadline of those schedulable objects is altered as specified by each schedulable object's respective scheduler.

Not currently implemented

Overrides:

setDeadline in class ReleaseParameters

Parameters:

deadline - The latest permissible completion time measured from the release time of the associated invocation of the schedulable object. If deadline is null, the deadline is set to a new instance of RelativeTime equal to period.

Throws:

java.lang.IllegalArgumentException - Thrown if the time value of deadline is less than or equal to zero, or if the new value of this deadline is incompatible with the scheduler for any associated schedulable object.

IllegalAssignmentError - Thrown if deadline cannot be stored in this.

setIfFeasible

public boolean setIfFeasible(RelativeTime period,
                             RelativeTime cost,
                             RelativeTime deadline)

This method first performs a feasibility analysis using the new period, cost and deadline attributes as replacements for the matching attributes of this. If the resulting system is feasible the method replaces the current attributes of this. If this parameter object is associated with any schedulable object (by being passed through the schedulable object's constructor or set with a method such as RealtimeThread.setReleaseParameters(ReleaseParameters)) the parameters of those schedulable objects are altered as specified by each schedulable object's respective scheduler.

Not currently implemented

Parameters:

period - The proposed period. There is no default value. If period is null an exception is thrown.

cost - The proposed cost. If null, the default value is a new instance of RelativeTime(0,0).

deadline - The proposed deadline. If null, the default value is new instance of RelativeTime(period).

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown if the period is null or its time value is not greater than zero, or if the time value of cost is less than zero, or if the time value of deadline is not greater than zero. Also thrown if the values are incompatible with the scheduler for any of the schedulable objects which are presently using this parameter object.

IllegalAssignmentError - Thrown if period, cost or deadline cannot be stored in this.

setPeriod

public void setPeriod(RelativeTime period)

Sets the period.

Parameters:

period - The value to which period is set.

Throws:

java.lang.IllegalArgumentException - Thrown if the given period is null or its time value is not greater than zero.

IllegalAssignmentError - Thrown if period cannot be stored in this.

setStart

public void setStart(HighResolutionTime start)

Sets the start time.

The effect of changing the start time for any schedulable objects associated with this parameter object is determined by the scheduler associated with each schedulable object.

Note: An instance of PeriodicParameters may be shared by several schedulable objects. A change to the start time may take effect on a subset of these schedulable objects. That leaves the start time returned by getStart unreliable as a way to determine the start time of a schedulable object.

Parameters:

start - The new start time. If null, the default value is a new instance of RelativeTime(0,0).